.\" Copyright (C) 2003-2007  Dmitry V. Levin <ldv@altlinux.org>
.\" 
.\" Documentation for the hasher project.
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\" 
.TH "HASHER" "7" "January 2007" "hasher @VERSION@" "ALT Linux"
.SH "NAME"
hasher \- modern safe package building technology
.SH "SYNOPSIS"
.B hsh
.IR "" [ options ]
.I <path\-to\-workdir>
.IR <package> ...
.SH "RATIONALE"
Long ago, when instrumental OS distributions made by few developers were
small enough to be placed on a single CD with sources, there was no real
package building technology.  Developers built their packages in the host
system created by installing the whole OS distribution.

Nowadays instrumental OS distributions are made by dozens of developers.
They are too large to be installed wholly.  As a result, traditional
package building scheme in the host system no longer fits the
requirements: it is insecure, unsafe and awkward.
.SH "REQUIREMENTS"
Modern package building technology should:
.TP
1.
not lower the host system security;
.TP
2.
protect itself from attacks installed by packages;
.TP
3.
protect package builds from attacks installed by other packages;
.TP
4.
ensure reliability of build results;
.TP
5.
provide reasonable performance.
.SH "ARCHITECTURE"
The
.B hasher
architecture is based on triple\-user model: caller user
.IR "" ( C )
and two unprivileged pseudousers; the first one
.IR "" ( R )
emulates root in the generated build environment, the second one
.IR "" ( U )
emulates a regular user who builds software.

Switching between caller user and helper users is handled by a special
privileged program
.BR hasher\-priv (8).
It is written with extreme caution to defend from attacks
installed by unprivileged users.  This helper is also used to purge
processes left after pseudousers, to create device files, and to
control resources allocated for unprivileged processes to defend from
DoS\-attacks.

In general, the way of source package in hasher during the build
process looks as follows:
.TP
1. Generate aptbox.
User
.I C
generates environment (aptbox) for apt.
.TP
2. Remove build environment probably left by previous builds.
The removal is done sequentially: inside build chroot by user
.IR U ,
inside build chroot by user
.I R
and finally outside chroot by user
.IR C .
.TP
3. Generate new build chroot framework.
User
.I C
generates the framework, which consists of helper directories
and statically linked helper programs:
.BR ash (1),
.BR find (1)
and
.BR cpio (1).
Basic device files are also created at this point by means of 
.BR hasher\-priv (8).
These devices are necessary for build environment and are secure
for the host system.
.TP
4. Generate basic install environment.
This environment contains everything necessary for regular package
installs.
User
.I C
using apt utilities determines set of packages requires to generate
install environment.
User
.I R
using static helper programs unpacks these packages.
.TP
5. Generate basic build environment.
This environment contains tools required for every package build.
User
.I C
using apt utilities determines set of packages, user
.I R
installs them.
.TP
6. Generate build environment for this particular package.
User
.I U
fetches package build dependencies, user
.I C
using apt utilities determines set of packages to install, and user
.I R
installs them.
.TP
7. Build the package.
User
.I U
executes the build.
.PP
These schemes are designed to eliminate attacks of the type
.IR U "\->" R ,
.IR U "\->" C ,
.IR R "\->" C ,
and all attacks targeted to root.

In order to increase performance essential when building a lot of packages,
.B hasher
does caching of the basic build environment.  It allows to skip steps 4 and 5.
.SH "AUTHOR"
Written by Dmitry V. Levin <ldv@altlinux.org>
.SH "REPORTING BUGS"
Report bugs to http://bugs.altlinux.ru/
.SH "COPYRIGHT"
Copyright \(co 2003-2007  Dmitry V. Levin <ldv@altlinux.org>
.br
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
.BR hsh (1),
.BR hasher\-priv.conf (5),
.BR hasher\-priv (8),
.BR hasher\-useradd (8),
.BR /usr/share/doc/hasher\-@VERSION@/QUICKSTART .
